Skip to main content

Arbitrary Message Bridge

You can also send arbitrary data between Gnosis and Ethereum using the native Arbitrary Message Bridge (AMB). This allows Gnosis contracts to send data and trigger contract functions on Ethereum and other chains, and vice versa.

The AMB is a key bridge primitive that is used inside higher-order bridges like the Omnibridge native token bridge.

The AMB currently supports Ethereum, and is part of the Tokenbridge Architecture. There may be additional EVM-based networks supported in the future.

With Telepathy added as the 8th validator, AMB bridge is now more secure with trustless zero-knowledge light client technology. Due to the light client finality requirements (at least 12mins on Ethereum), the transactions will take approx. 30mins to be signed by the bridge. However, users can still use 3rd party bridges (Jumper.exchange, Connext, Hop) without any impact. For more details, check out how AMB & Omnibridge works with Telepathy validator.

Key Information​

Overview​

Detail
Frontend URLN/A
Trust Model4-of-8 Validator Multisig
Governance8-of-16 Multisig
Governance Parameters
Bug Bountyup to $2m
Bug ReportingImmunefi

Fees & Daily Limits​

As the Arbitrary Message Bridge is a message passing bridge, there are no fees or daily limits associated with it.

Bridge Validators​

For a message/tokens to be relayed to another network, bridge validators need to affirm the transaction. Bridge validators are run by trusted members of the Gnosis community and ZK Light Client validator Telepathy.

Current Bridge Validators​

GC AddressOrganization Name
gno:0x459a3bd49f1ff109bc90b76125533699aaaaf9a6Protofire
gno:0x105CD22eD3D089Bf5589C59b452f9dE0796Ca52dGiveth
gno:0xfa98b60e02a61b6590f073cad56e68326652d094Karpatkey
gno:0xbdc141c8d2343f33f40cb9edd601ccf460cd0ddeGnosisDAO
gno:0x674c97db4ce6cac04a124d745979f3e4cba0e9f0Cow Protocol
gno:0x258667E543C913264388B33328337257aF208a8fGnosis Safe
gno:0x90776017057b84bc47D7e7383b65C463C80a6cddGateway
gno:0x456c255A8BC1F33778603A2a48Eb6B0C69F4d48ETelepathy

Bridge Governance​

Key Contracts​

References:

Ethereum​

ContractAddress
AMB/Omnibridge Multi-Token Mediator0x88ad09518695c6c3712AC10a214bE5109a655671
AMB Contract Proxy (Foreign)0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e
AMB/OmniBridge wETH Router Helper0xa6439Ca0FCbA1d0F80df0bE6A17220feD9c9038a

How it works​

Terminology​

  • Home (Native) Network: Of the two networks being bridged between, the home or native network is the one with fast and inexpensive operations. All bridge operations to collect validator confirmations are performed on this side of the bridge.
  • Foreign Network: Can be any EVM chain, generally it refers to Ethereum.
  • Originating Contract: An arbitrary contract where the message originates, typically this is where the user interacts and requests for a function to be invoked on another network.

Call a cross-chain method via AMB:​

function requireToPassMessage (address _contract,
                                bytes _data,
                                uint256 _gas) external;
paramdetails
_contractaddress of contract on other network
_dataencoded bytes of the method selector and the params that will be called in the contract on the other side
_gasgas to be provided in execution of the method call on the other side

Foreign Network to Home Network​

  1. User calls foo() on the originating contract
  2. Originating contract calls requireToPassMessage() on Foreign Bridge contract, and encodes foo(), target address, and includes some tokens for gas.
  3. UserRequestForAffirmation event is emitted, and listening validators relay the message to the Home side where signatures are collected
  4. executeAffirmation() is called on the Home Bridge contract by a validator once enough signatures are collected.
  5. Home bridge contract decodes the message and calls foo() on the target contract.

Home Network to Foreign Network​

  1. User calls foo() on an originating contract
  2. Originating contract calls requireToPassMessage() on Home Bridge contract, and encodes foo(), target address, and includes some tokens for gas.
  3. Signatures are collected from validators, and once enough are collected requireToConfirmMessage() is called
  4. Message is relayed to the Foreign Bridge contract, and executeSignatures() is called
  5. Foreign bridge contract decodes the message and calls foo() on target contract

AMB Bridge proxy contact on Ethereum
AMB Bridge Proxy Contract in Gnosis

How it works with Telepathy validator​

AMB&Omnibridge with Telepathy Validator

** In the graph above, light green compoenents work as the same as Call a cross-chain method via AMB on the previous section.

There are 5 key components for Telepathy validator in AMB & Omnibridge:

Off chain

  1. Telepathy Relayer: Provide merkle proof for Telepathy PubSub, that the userRequestForAffirmation event was emitted on Ethereum.
  2. Telepathy Operator: For every ~12 mins (2 epoch in Ethereum), call Telepathy Light Client to update header.

On Gnosis Chain

  1. Telepathy PubSub: Verify the Merkle proof against the block header and publish the event.
  2. Telepathy Light Client: Generate a proof of consensus for block header and verify on-chain.
  3. Telepathy Validator: Subscribe to UserRequestForAffirmation event, and handle the published event by calling executeAffirmation() on AMB.

Once the user initiate cross-chain method via AMB on Ethereum, it will take ~12 mins for the transaction to get finalized in block and for Telepathy light client to obtain the block header information. Thus, user has to wait for approx. 30 mins for the message to get bridged to Gnosis Chain.

RoleAddress
Telepathy PubSub0xa96c29A4114B414543Bdc9be5616dE270b9e88ec
Telepathy Validator0x456c255A8BC1F33778603A2a48Eb6B0C69F4d48E

For more details, check out Telepathy Validator for Omnibridge and https://docs.telepathy.xyz/.

How to check if AMB is down (not relaying message)​

In certain circumstances, i.e. hardfork, AMB will be planned for downtime (not relaying message) to ensure security of the bridge. Planned downtime will be announced in public channel like Discord and Twitter, prior to the event.
There is also another way to check whether the AMB is down or not by reading maxGasPerTx value on AMB contract.

In the current configuration, maxGasPerTx is set to 4000000 on Ethereum and 2000000 on Gnosis Chain.

The AMB is down when maxGasPerTx is set to 0, only by owner of the contract.

By setting maxGasPerTx to 0, the condition in _sendMessage() will not pass, meaning, the bridge is down/stopped.

Security Considerations for Receiving a Call​

ConcernRemediation
AuthorizationCheck the address of invoking contract using messageSender()
AuthorizationCheck that msg.sender is the address of the bridge contract
Replay AttacktransactionHash() allows for checking of a hash of the transaction that invoked the requireToPassMessage() call. The invoking contract (in some cases, the mediator contract) is responsible for providing a unique sequence (can be a nonce) as part of the _data param in the requireToPassMessage() function call

Mediator Contracts​

A mediator contract is needed if there is an approval flow, such as when transferring an NFT or ERC-20 token. For a more in-depth explanation, see the Omnibridge page.

AMB Components​

ComponentDescription
System ContractsAMB Implementation Contracts (Home Bridge and Foreign Bridge), Governance Multisigs, gas limit helpers, failed call management helpers (for when gas estimate was insufficient), and fee management helpers to collect fees
OraclesContainerized microservices that listen for on-chain events and send confirmations to relay messages. More on them here.
DevOpsBridge monitoring, ALM, docker compose, ansible playbooks
dApp Contractsextensions (pair mediator contracts on both sides of the AMB), such as the Omnibridge

Uses of AMB​

  • ERC-to-ERC Bridges: AMB-ERC-TO-ERC mode enables the transfer of ERC tokens to the Foreign Mediator, which will interact with Foreign AMB Bridge to mint wrapped ERC-667 tokens on the Home Network. Complimentarily, the mode enables the transfer ERC20 or ERC-667 tokens to the Home Mediator, which will interact with Home AMB Bridge to unlock ERC20 tokens on the Foreign network. This is used by the Omnibridge.
  • ERC-to-Native Bridges: ERC-TO-NATIVE mode enables the user to send ERC20 tokens to the Foreign Bridge and receive native coins from the Home Bridge Complimentarily, then can send native coins to the Home Bridge to unlock ERC20 tokens from the Foreign Bridge. The home network nodes must support a consensus engine that allows using a smart contract for block reward calculation. This mode is used by the xDai Bridge
  • Message Passing: ARBITRARY-MESSAGE mode enables the capability to invoke a Home/Foreign Bridge contract to send a message that will be executed on the other Network. This can be an arbitrary contract method invocation.

Managing Bridge Contracts​

Bridge Roles​

  • Administrator role (representation of a multisig contract):
    • add/remove validators
    • set daily limits on either direction
    • set maximum per transaction limit on both bridges
    • set minimum per transaction limit on both bridges
    • upgrade contracts in case of vulnerability
    • set minimum required signatures from validators in order to relay a user's transaction
  • Validator role:
    • provide 100% uptime to relay transactions
    • listen for UserRequestForSignature events on Home Bridge and sign an approval to relay assets on Foreign network
    • listen for CollectedSignatures events on Home Bridge. As soon as enough signatures are collected, transfer all collected signatures to the Foreign Bridge contract.
    • listen for UserRequestForAffirmation or Transfer (depending on the bridge mode) events on the Foreign Bridge and send approval to Home Bridge to relay assets from Foreign Network to Home
  • User role:
    • sends assets to Bridge contracts:
      • in ERC-TO-NATIVE mode: send ERC20 tokens to the Foreign Bridge to receive native coins from the Home Bridge, send native coins to the Home Bridge to unlock ERC20 tokens from the Foreign Bridge;
      • in ARBITRARY-MESSAGE mode: Invoke Home/Foreign Bridge to send a message that will be executed on the other Network as an arbitrary contract method invocation;
      • in AMB-ERC-TO-ERC mode: transfer ERC20 tokens to the Foreign Mediator which will interact with Foreign AMB Bridge to mint ERC20 tokens on the Home Network, and transfer ERC20 tokens to the Home Mediator which will interact with Home AMB Bridge to unlock ERC20 tokens on Foreign network.

Managing Bridge Validators​

Bridge admins can vote to add/remove validators. Read more about governance here

Resources​